<html>

<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<title>javax.microedition.io.file</title>
</head>

<body>

<p>This package describes file system access support based on the <code>Generic Connection Framework</code>.
<H2>FileConnection URL Format</H2>
<P>The format of the input string used to access a
FileConnection through<code> Connector.open()</code> must follow the format for
a fully qualified, absolute path file name as described in the file URL format
as part of IETF RFCs 1738 & 2396.  That RFC dictates that a file URL takes
the form:
</P>
<code>file://&lt;host&gt;/&lt;path&gt;
</code>
<P>In the form above, &lt;host&gt; is the fully qualified domain name of the
system on which the &lt;path&gt; is accessible, and &lt;path&gt; is a
hierarchical directory path of the form
<code>&lt;root&gt;/&lt;directory&gt;/&lt;directory&gt;/.../&lt;name&gt;</code>.
</P>
<P>
The file connection defines the first directory as the <I>root</I>, which
corresponds to a logical mount point for a particular storage unit or memory.
Root strings are defined by the platform or implementation and can be a string
of zero or more characters (the empty string &quot;&quot; can be a valid root string on some systems) 
followed by a trailing "/" to denote that the root is a directory. Each
root string is guaranteed to uniquely refer to a root. 
Root names are device specific and are not required
to adhere to any standard.  Examples of possible root strings include:
Examples of possible root strings and how to open them include:<br>
<table border=1>
<tr><th>Possible Root Value</th><th>Opening a FileConnection to the Root</th></tr>
<tr><td>CFCard/</td><td>Connector.open("file:///CFCard/");</td></tr>
<tr><td>SDCard/</td><td>Connector.open("file:///SDCard/");</td></tr>
<tr><td>MemoryStick/</td><td>Connector.open("file:///MemoryStick/");</td></tr>
<tr><td>C:/</td><td>Connector.open("file:///C:/");</td></tr>
<tr><td>/</td><td>Connector.open("file:////");</td></tr>
</table>
<P>
The valid <i> &lt;root&gt;</i> values for a device can be retrieved by
using the <code>FileSystemRegistry.listRoots()</code> method.
</P>
<P>
The file URL must be a full absolute path file name.&nbsp; Relative path names
(i.e. names that contain &quot;..&quot; or &quot;.&quot;) are not valid in the
API except where explicitly noted.
</P>
<h2>URL Character Format </h2>
<p>The Java class String is to encapsulate the character string of a URI in the <code>Connector.open()</code>
method.&nbsp; The Java String class is capable of containing Unicode characters
and therefore the file URI may be specified using Unicode characters.&nbsp;</p>
<p> However, RFC 2396 (used to define the file URI format) allows file URIs to
be expressed using an escaped ASCII format.&nbsp; In this scheme, Non-ASCII
characters are encoded using UTF-8 and the resulting bytes are
escaped using the &quot;%hh&quot; mechanism. The generic escaping mechanism and
valid character repertoire that can be presented literally are defined in the URI
specification [RFC 2396]. This canonical form of the URI is referred to in this
specification as &quot;<b><i>escaped
form</i></b>&quot;.&nbsp; If the escaping mechanism is not present in the URI,
the URI is said to be in&nbsp; &quot;<i><b>unescaped form</b></i>&quot;.&nbsp;
Any occurrence of the character &quot;%&quot; indicates that the URI provided is
in escaped form.&nbsp; To specify the percent character in a URI, the escaped
character sequence of &quot;%25&quot; must be used.</p>
<p>All of the methods in the <code>Connector</code> class accept both escaped
and unescaped forms of file URIs as valid file specifications.&nbsp; All methods
in the FileConnection API that accepts any part of the file URI accepts both
escaped and unescaped forms of the input parameter unless otherwise explicitly
stated.&nbsp; All methods in the FileConnection API that return any part of the
file URI return the values in unescaped form unless otherwise explicitly stated.</p>
<h2>File Separator Specification</h2>
<p>The FileConnection API returns and accepts only &quot;/&quot; as a file separator in File URIs and directory names.&nbsp;
However, a platform may use a different separator.&nbsp; This separator can be
retrieved via the system property &quot;file.separator&quot;, which is defined to contain the path separator used in
the given platform.&nbsp; Applications should replace the trailing &quot;/&quot; with
the file.separator value when presenting directories or path names in user interfaces.</p>
<h2>File Stream Behavior</h2>
<p> The behaviors of the methods <code>Connector.openInputStream</code>, <code>Connector.openDataInputStream</code>,
<code>Connector.openOutputStream,</code> and <code>Connector.openDataOutputStream</code> when a "file://" parameter is specified is
governed by the FileConnection methods of the same name.&nbsp; In other words, <code>Connector.openXXXStream</code>
is equivalent to invoking <code>FileConnection fs = Connector.open</code>
then <code>fs.openXXXStream</code>.</p>
<p>&nbsp;</p>
</body>
</html>
